<!doctype html>
<html lang="en" class="page-type-section">
<head prefix="og: http://ogp.me/ns#">
<meta charset="utf-8">
<title>2.3.17 - FreeMarker 手册</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="format-detection" content="telephone=no">
<meta property="og:site_name" content="FreeMarker 手册">
<meta property="og:title" content="2.3.17">
<meta property="og:locale" content="en_US">
<meta property="og:url" content="http://freemarker.org/docs/versions_2_3_17.html">
<link rel="canoical" href="http://freemarker.org/docs/versions_2_3_17.html">
<link rel="icon" href="favicon.png" type="image/png">
<link rel="stylesheet" type="text/css" href="docgen-resources/docgen.min.css">
</head>
<body itemscope itemtype="https://schema.org/Code">
    <meta itemprop="url" content="http://freemarker.org/docs/">
    <meta itemprop="name" content="FreeMarker 手册">

  <!--[if lte IE 9]>
  <div style="background-color: #C00; color: #fff; padding: 12px 24px;">Please use a modern browser to view this website.</div>
  <![endif]--><div class="header-top-bg"><div class="site-width header-top"><a class="logo" href="http://freemarker.org" role="banner">            <img itemprop="image" src="logo.png" alt="FreeMarker">
</a><ul class="tabs"><li><a href="http://freemarker.org/">Home</a></li><li class="current"><a href="index.html">Manual</a></li><li><a class="external" href="http://freemarker.org/docs/api/index.html">Java API</a></li></ul><ul class="secondary-tabs"><li><a class="tab icon-heart" href="http://freemarker.org/contribute.html" title="Contribute"><span>Contribute</span></a></li><li><a class="tab icon-bug" href="https://sourceforge.net/p/freemarker/bugs/new/" title="Report a Bug"><span>Report a Bug</span></a></li><li><a class="tab icon-download" href="http://freemarker.org/freemarkerdownload.html" title="Download"><span>Download</span></a></li></ul></div></div><div class="header-bottom-bg"><div class="site-width search-row"><a href="toc.html" class="navigation-header">Manual</a><div class="navigation-header"></div></div><div class="site-width breadcrumb-row"><ul class="breadcrumb" itemscope itemtype="http://schema.org/BreadcrumbList"><li class="step-0" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="toc.html"><span itemprop="name">FreeMarker 手册</span></a></li><li class="step-1" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="app.html"><span itemprop="name">附录</span></a></li><li class="step-2" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="app_versions.html"><span itemprop="name">版本历史</span></a></li><li class="step-3" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="versions_2_3_17.html"><span itemprop="name">2.3.17</span></a></li></ul><div class="bookmarks" title="Bookmarks"><span class="sr-only">Bookmarks:</span><ul class="bookmark-list"><li><a href="alphaidx.html">Alpha. index</a></li><li><a href="gloss.html">Glossary</a></li><li><a href="dgui_template_exp.html#exp_cheatsheet">Expressions</a></li><li><a href="ref_builtins_alphaidx.html">?builtins</a></li><li><a href="ref_directive_alphaidx.html">#directives</a></li><li><a href="ref_specvar.html">.spec_vars</a></li><li><a href="app_faq.html">FAQ</a></li></ul></div></div></div>    <div class="main-content site-width">
      <div class="content-wrapper">
  <div id="table-of-contents-wrapper" class="col-left">
      <script>var breadcrumb = ["FreeMarker 手册","附录","版本历史","2.3.17"];</script>
      <script src="toc.js"></script>
      <script src="docgen-resources/main.min.js"></script>
  </div>
<div class="col-right"><div class="page-content"><div class="page-title"><div class="pagers top"><a class="paging-arrow previous" href="versions_2_3_18.html"><span>Previous</span></a><a class="paging-arrow next" href="versions_2_3_16.html"><span>Next</span></a></div><div class="title-wrapper">
<h1 class="content-header header-section1" id="versions_2_3_17" itemprop="headline">2.3.17</h1>
</div></div><div class="page-menu">
<div class="page-menu-title">Page Contents</div>
<ul><li><a class="page-menu-link" href="#autoid_161" data-menu-target="autoid_161">Changes on the FTL side</a></li><li><a class="page-menu-link" href="#autoid_162" data-menu-target="autoid_162">Changes on the Java side</a></li><li><a class="page-menu-link" href="#autoid_163" data-menu-target="autoid_163">Other changes</a></li></ul> </div><p>Date of release: 2011-05-17</p><p>It&#39;s possibly urgent to update to this version because of a
        <a href="#v2317secfix">security fix</a>!</p>
          



<h2 class="content-header header-section2" id="autoid_161">Changes on the FTL side</h2>


          <ul>
            <li>
              <p><code class="inline-code">?seq_index_of</code> and
              <code class="inline-code">?seq_last_index_of</code> now works on collections
              (<code class="inline-code">freemarker.template.TemplateCollectionModel</code>-s)
              too, not only on sequences
              (<code class="inline-code">freemarker.template.TemplateSequenceModel</code>-s).</p>
            </li>

            <li>
              <p><code class="inline-code">?long</code> now works for date, date-time or
              time values, and returns the milliseconds since the epoch (as
              <code class="inline-code">java.util.Date.getTime()</code>).</p>
            </li>

            <li>
              <p>To convert numbers (usually Java
              <code class="inline-code">long</code>-s) to date or date-time and time values,
              <code class="inline-code">?number_to_date</code>,
              <code class="inline-code">?number_to_time</code>,
              <code class="inline-code">?number_to_datetime</code> was added. <a href="ref_builtins_expert.html#ref_builtin_numToDate">See more here...</a>
              (Unfortunately, <code class="inline-code">?date</code> and like can&#39;t be
              extended to support this due to backward compatibility
              issues.)</p>
            </li>

            <li>
              <p>New built-ins to format numbers with ISO 8601 &quot;extended&quot;
              format regardless of the current date/time formatting settings,
              and even regardless of the current time zone setting. For
              example <code class="inline-code">${myTimeStamp?iso_utc}</code> will print
              something like <code class="inline-code">2010-05-16T23:05:45Z</code>. <a href="ref_builtins_date.html#ref_builtin_date_iso">See more here...</a></p>
            </li>

            <li>
              <p>New <a href="ref_specvar.html">special variable</a>,
              <code class="inline-code">now</code>. This returns the current date-time.
              Usage examples: &quot;<code class="inline-code">Page generated: ${.now}</code>&quot;,
              &quot;<code class="inline-code">Today is ${.now?date}</code>&quot;, &quot;<code class="inline-code">The
              current time is ${.now?time}</code>&quot;.</p>
            </li>

            <li>
              <p><code class="inline-code">?sort</code> and <code class="inline-code">?sort_by</code>
              now supports sorting boolean values.</p>
            </li>

            <li>
              <p>When using unsupported or unknown <a href="ref_builtins_string.html#ref_builtin_string_flags">string built-in flags</a>,
              FreeMarker will now <a href="pgui_misc_logging.html">log</a>
              warnings (maximum 25 times per class-loader, to prevent flooding
              the log). It&#39;s certain that starting from FreeMarker 2.4 these
              will count as errors.</p>
            </li>

            <li>
              <p>Bug fixed <a href="http://sourceforge.net/tracker/?func=detail&amp;atid=100794&amp;aid=3047201&amp;group_id=794">[3047201]</a>:
              Using regular expressions (like with <code class="inline-code">?match</code>)
              could cause lockup in multi-threaded environment, also memory
              leakage when using dynamically generated regular
              expressions.</p>
            </li>

            <li>
              <p>Bug fixed: <code class="inline-code">?seq_contains</code>,
              <code class="inline-code">?seq_index_of</code> and
              <code class="inline-code">?seq_last_index_of</code> has failed with
              non-<code class="inline-code">java.util.List</code>
              <code class="inline-code">java.util.Collection</code>-s that are wrapped with
              pure <code class="inline-code">BeansWrapper</code> (not the
              <code class="inline-code">DefaultObjectWrapper</code>) as
              <code class="inline-code">TemplateSequenceModel</code>. (See also:
              <code class="inline-code">getSupportsIndexedAccess()</code> below)</p>
            </li>
          </ul>
        
          



<h2 class="content-header header-section2" id="autoid_162">Changes on the Java side</h2>


          <ul>
            <li>
              <p><a name="v2317secfix"></a><em>Security fix</em>:
              Using carefully crafted template names (template paths) that
              contain code point 0 (<code class="inline-code">&#39;\u0000&#39;</code>), it was
              possible to load files from outside the template root directory
              like if they were FreeMarker templates. The root of the problem
              is that the underlying native C/C++ part (which belongs to the
              Java platform or to the OS) interprets the 0 as the end of the
              string, while Java (and hence FreeMarker and the Servlet
              container) doesn&#39;t. Thus a path that looked safe for FreeMarker
              become unsafe on the lower level. The problem is present with
              all ways of loading templates by name
              (<code class="inline-code">Configuration.getTemplate(<em class="code-color">...</em>)</code>,
              <code class="inline-code">&lt;#include
              <em class="code-color">...</em>&gt;</code>,
              <code class="inline-code">&lt;#import
              <em class="code-color">...</em>&gt;</code>).</p>

              <p>You are not affected if you don&#39;t allow users to upload
              templates and also at least one of these stands:</p>

              <ul>
                <li>
                  <p>In your system users can&#39;t provide arbitrary strings
                  as template names (template paths). For example, if users
                  are only allowed to visit the URL-s that belong to the MVC
                  Controller (like they can&#39;t visit <code class="inline-code">*.ftl</code>)
                  then they can&#39;t suggest arbitrary template names.</p>
                </li>

                <li>
                  <p>The template names are part of the path in the Web
                  page URL, and your webserver or Servlet container disallows
                  URL-s that contain <code class="inline-code">%00</code>, or terminate the
                  URL at it before passing it to the servlets.</p>
                </li>

                <li>
                  <p>You are using <code class="inline-code">FileTemplateLoader</code>
                  and linking is not allowed in it (by default it isn&#39;t
                  allowed).</p>
                </li>
              </ul>
            </li>

            <li>
              <p>FreeMarker now can log its messages directly using SLF4J
              or Apache Commons Logging. However, it will not use these logger
              libraries automatically, until 2.4; <a href="pgui_misc_logging.html">see more here...</a> But it&#39;s
              recommended to switch to SLF4J now.</p>
            </li>

            <li>
              <p>New setting: <code class="inline-code">&quot;auto_flush&quot;</code>,
              <code class="inline-code">Configurable.setAutoFlush(boolean)</code>. Sets
              whether the output <code class="inline-code">Writer</code> is automatically
              flushed at the end of <code class="inline-code">Template.process(Object,
              Writer)</code> (and its overloads). The default is
              <code class="inline-code">true</code>, which corresponds to the earlier
              behavior. Using <code class="inline-code">false</code> is needed for example
              when a Web page is composed from several boxes (like portlets,
              GUI panels, etc.) that aren&#39;t inserted with
              <code class="inline-code">#include</code> (or with similar directives) into a
              master FreeMarker template, rather they are all processed with a
              separate
              <code class="inline-code">Template.process(<em class="code-color">...</em>)</code>
              call. In a such scenario the automatic flushes would commit the
              HTTP response after each box, hence interfering with full-page
              buffering, and also possibly decreasing performance with too
              frequent and too early response buffer flushes.</p>
            </li>

            <li>
              <p>Added new setting:
              <code class="inline-code">Configuration.setNewBuiltinClassResolver(TemplateClassResolver)</code>,
              or <code class="inline-code">new_builtin_class_resolver</code> property. This
              allows you to specify how the <a href="ref_builtins_expert.html#ref_builtin_new"><code>new</code> built-in</a>
              (like in <code class="inline-code">&quot;com.example.SomeClass&quot;?new()</code>)
              resolves classes and which classes are accessible at all. If you
              are allowing not-so-much-trusted users to upload templates, you
              should be definitely interested; see the Java API docs of
              <code class="inline-code">freemarker.core.Configurable.setSetting</code> and
              <code class="inline-code">freemareker.template.Configuration.setNewBuiltinClassResolver</code>.
              Otherwise it&#39;s still recommended to set this to
              <code class="inline-code">TemplateClassResolver.SAFER_RESOLVER</code> (or
              <code class="inline-code">safer</code> if you are using properties), although
              that&#39;s not 100% backward compatible (see Java API docs) .</p>
            </li>

            <li>
              <p>Added
              <code class="inline-code">freemarker.cache.NullCacheStorage</code>: Setting
              this as the cache storage in <code class="inline-code">Configuration</code>
              disables caching.</p>
            </li>

            <li>
              <p>Added <code class="inline-code">getSupportsIndexedAccess()</code> to
              <code class="inline-code">freemarker.ext.beans.CollectionModel</code>, so one
              can check if <code class="inline-code">TemplateSequenceModel.get(int)</code>
              will work with a particular <code class="inline-code">CollectionModel</code>
              instance or not.</p>
            </li>

            <li>
              <p>Bug fixed <a href="http://sourceforge.net/tracker/?func=detail&amp;aid=2992265&amp;group_id=794&amp;atid=100794">[2992265]</a>:
              JSP <code class="inline-code">FreeMarkerPageContext.include</code> behaved
              incorrectly.</p>
            </li>

            <li>
              <p>Bug fixed: When using FreeMarker&#39;s JSP support with JSP
              tags that use
              <code class="inline-code">javax.servlet.jsp.PageContext.pushBody</code> (like
              some Stripes tags), <code class="inline-code">&quot;ArrayIndexOutOfBoundsException:
              -1&quot;</code> occurred inside
              <code class="inline-code">freemarker.ext.jsp.FreeMarkerPageContext.popWriter</code>.</p>
            </li>

            <li>
              <p>Bug fixed <a href="http://sourceforge.net/tracker/?func=detail&amp;atid=100794&amp;aid=3033015&amp;group_id=794">[3033015]</a>:
              <code class="inline-code">AllHttpScopesHashModel</code> used
              <code class="inline-code">WrappingTemplateModel.getDefaultObjectWrapper()</code>
              for wrapping variables in the page scope, while used the
              user-specified <code class="inline-code">ObjectWrapper</code> for all other
              scopes (request, session, etc.). Now it uses the user-specified
              wrapper in the page scope as well.</p>
            </li>

            <li>
              <p>Bug fixed <a href="https://sourceforge.net/tracker/?func=detail&amp;aid=3128073&amp;group_id=794&amp;atid=100794">[3128073]</a>:
              <code class="inline-code">HashAdapther.containsKey(...)</code> returned
              <code class="inline-code">true</code> for a key that doesn&#39;t exist when
              unwrapping the key has failed. As a side effect of the fix,
              <code class="inline-code">BeansWrapper.CAN_NOT_UNWRAP</code> is now private;
              earlier it was public by mistake.</p>
            </li>

            <li>
              <p>Big fixed <a href="http://sourceforge.net/tracker/?func=detail&amp;aid=3151085&amp;group_id=794&amp;atid=100794">[3151085]</a>:
              <code class="inline-code">freemarker.jsp.TaglibFactory</code> didn&#39;t locate
              tld files properly. This fix gives better compliance with JSP
              specification for resolving and loading tld files.</p>
            </li>

            <li>
              <p>Bug fixed: Unwrapping <code class="inline-code">null</code> with a
              <code class="inline-code">BeansWrapper</code> that had a custom null-model
              didn&#39;t result in <code class="inline-code">null</code>. Now both unwrapping
              <code class="inline-code">null</code> and the custom null-model gives
              <code class="inline-code">null</code>.</p>
            </li>

            <li>
              <p>Log messages doesn&#39;t contain line-breaks (CR or LF)
              anymore and quote paths and other arbitrary text with Java
              string literal syntax that also escapes <code class="inline-code">&lt;</code>
              characters as <code class="inline-code">\u003C</code>. These address security
              concerns related to poor quality log appenders and buggy log
              readers. This change is mostly noticeable on template processing
              error entries, which will now quote the exception message. Note
              that how stack traces (the <code class="inline-code">Throwable</code> objects)
              are logged is still up to the logging framework you are
              using.</p>
            </li>
          </ul>
        
          



<h2 class="content-header header-section2" id="autoid_163">Other changes</h2>


          <ul>
            <li>
              <p>The DTD-s and XSD-s that are included in
              <code class="inline-code">freemarker.jar</code> under
              <code class="inline-code">freemarker/ext/jsp</code> are now under Apache
              Software License, Version 2. This is also clarified in the
              <code class="inline-code">LICENSE.txt</code>. Earlier these files had no clear
              license terms.</p>
            </li>
          </ul>
        <div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="versions_2_3_18.html"><span>Previous</span></a><a class="paging-arrow next" href="versions_2_3_16.html"><span>Next</span></a></div></div></div></div>      </div>
    </div>
<div class="site-footer"><div class="site-width"><div class="footer-top"><div class="col-left sitemap"><div class="column"><h3 class="column-header">Overview</h3><ul><li><a href="http://freemarker.org/index.html">What is FreeMarker?</a></li><li><a href="http://freemarker.org/freemarkerdownload.html">Download</a></li><li><a href="app_versions.html">Version history</a></li><li><a href="http://freemarker.org/history.html">About us</a></li><li><a itemprop="license" href="app_license.html">License</a></li></ul></div><div class="column"><h3 class="column-header">Handy stuff</h3><ul><li><a href="http://freemarker-online.kenshoo.com/">Try template online</a></li><li><a href="dgui_template_exp.html#exp_cheatsheet">Expressions cheatsheet</a></li><li><a href="ref_directive_alphaidx.html">#directives</a></li><li><a href="ref_builtins_alphaidx.html">?built_ins</a></li><li><a href="ref_specvar.html">.special_vars</a></li></ul></div><div class="column"><h3 class="column-header">Community</h3><ul><li><a href="https://github.com/nanlei/freemarker/tree/manual-zh-2.3-gae/src/manual">Chinese Manual on Github</a></li><li><a href="https://github.com/freemarker/freemarker">FreeMarker on Github</a></li><li><a href="https://twitter.com/freemarker">Follow us on Twitter</a></li><li><a href="https://sourceforge.net/p/freemarker/bugs/new/">Report a bug</a></li><li><a href="http://stackoverflow.com/questions/ask?tags=freemarker">Ask a question</a></li><li><a href="http://freemarker.org/mailing-lists.html">Mailing lists</a></li></ul></div></div><div class="col-right"><ul class="social-icons"><li><a class="github" href="https://github.com/freemarker/freemarker">Github</a></li><li><a class="twitter" href="https://twitter.com/freemarker">Twitter</a></li><li><a class="stack-overflow" href="http://stackoverflow.com/questions/ask?tags=freemarker">Stack Overflow</a></li></ul><a class="xxe" href="http://www.xmlmind.com/xmleditor/" rel="nofollow" title="Edited with XMLMind XML Editor"><span>Edited with XMLMind XML Editor</span></a></div></div><div class="footer-bottom"><p><span class="generated-for-product">Generated for: Freemarker 2.3.23</span><span class="last-updated"> Last generated:
<time itemprop="dateModified" datetime="2015-09-18T14:38:51Z" title="Friday, September 18, 2015 2:38:51 PM GMT">2015-09-18 14:38:51 GMT</time></span></p> <p class="copyright">
© <span itemprop="copyrightYear">1999</span>–2015
<a itemtype="http://schema.org/Organization" itemprop="copyrightHolder" href="http://freemarker.org">The FreeMarker Project</a>. All rights reserved. </p>
</div></div></div></body>
</html>
